home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 October: Mac OS SDK / Dev.CD Oct 96 SDK / Dev.CD Oct 96 SDK1.toast / Development Kits (Disc 1) / AppleScript / Development Tools / Interfaces / AppleScript 1.0 Interfaces / CIncludes / OSA.h < prev    next >
Encoding:
Text File  |  1993-04-08  |  49.5 KB  |  1,272 lines  |  [TEXT/MPS ]
  1. ////////////////////////////////////////////////////////////////////////////////
  2. // OPEN SCRIPTING ARCHITECTURE: Client Interface
  3. ////////////////////////////////////////////////////////////////////////////////
  4. // Copyright © 1992 Apple Computer, Inc. All rights reserved.
  5. // Authors: Jens Alfke, William Cook, Donn Denman, and Warren Harris
  6. ////////////////////////////////////////////////////////////////////////////////
  7. // This interface defines what it means to be a "scripting component."
  8. // Scripting components allow "scripts" to be loaded and executed.  This
  9. // interface does not define the way in which a particular scripting
  10. // component's scripts are editing and debugged.
  11. ////////////////////////////////////////////////////////////////////////////////
  12.  
  13. #ifndef __OSA__
  14. #define __OSA__
  15.  
  16. #ifndef __APPLEEVENTS__
  17. #include <AppleEvents.h>
  18. #endif
  19. #ifndef __AEOBJECTS__
  20. #include <AEObjects.h>
  21. #endif
  22. #ifndef __COMPONENTS__
  23. #include <Components.h>
  24. #endif
  25.  
  26. #ifdef __cplusplus
  27. extern "C" {
  28. #endif
  29.  
  30. //////// Conditional Compilation
  31.  
  32. // component implements can define this macro eliminate the inlines
  33. #ifndef OSAComponentFunctionInline
  34. #define OSAComponentFunctionInline(a, b)        = ComponentCallNow(a, b)
  35. #endif 
  36.  
  37. ////////////////////////////////////////////////////////////////////////////////
  38. // Types and Constants
  39. ////////////////////////////////////////////////////////////////////////////////
  40.  
  41. #define kOSAComponentType                        'osa '
  42.     // The componenent manager type code for components that
  43.     // support the OSA interface defined here.
  44.  
  45. #define kOSAGenericScriptingComponentSubtype    'scpt'
  46.  
  47. #define kOSAFileType                            'osas'
  48.     // Type of script document files.
  49.  
  50. typedef ComponentResult                            OSAError;
  51.     // Under the Open Scripting Architecture all error results are longs.
  52.  
  53. typedef unsigned long                            OSAID;
  54.     // OSAIDs allow transparent manipulation of scripts associated with
  55.     // various scripting systems.
  56.  
  57. #define kOSANullScript                            ((OSAID) 0)        
  58.     // No-script constant. 
  59.  
  60. #define kOSANullMode                            0    // sounds better
  61. #define kOSAModeNull                            0    // tastes consistent
  62.     // Some routines take flags that control their execution.  This constant
  63.     // declares default mode settings are used.
  64.  
  65. #define kOSASuite                                'ascr'
  66. #define kOSARecordedText                        'recd'
  67.     // Suite and event code of the RecordedText event. (See OSAStartRecording,
  68.     // below.)
  69.  
  70. ////////////////////////////////////////////////////////////////////////////////
  71. // API Errors
  72. ////////////////////////////////////////////////////////////////////////////////
  73.  
  74. #define errOSASystemError                    -1750
  75. #define    errOSAInvalidID                        -1751
  76. #define errOSABadStorageType                -1752
  77. #define errOSAScriptError                    -1753
  78. #define errOSABadSelector                    -1754
  79. #define errOSASourceNotAvailable            -1756
  80. #define errOSANoSuchDialect                    -1757
  81. #define errOSADataFormatObsolete            -1758
  82. #define errOSADataFormatTooNew                -1759
  83. #define errOSACorruptData                    errAECorruptData
  84. #define errOSARecordingIsAlreadyOn            errAERecordingIsAlreadyOn
  85.  
  86. ////////////////////////////////////////////////////////////////////////////////
  87. // Standard Script Errors
  88. ////////////////////////////////////////////////////////////////////////////////
  89. // It is recommended that scripting components use the following set of error
  90. // codes to signal failure when applicable.  This enables applications that
  91. // use the OSA API to deal with some class of script errors in a less than 
  92. // ad hoc manner.  Scripting components are of course encouraged to return
  93. // component-specific errors when these don't apply.
  94. ////////////////////////////////////////////////////////////////////////////////
  95.  
  96. //////// Dynamic errors:
  97. //
  98. // These errors result from data-dependent conditions and are typically
  99. // signaled at runtime.
  100.  
  101. #define errOSACantCoerce                    errAECoercionFail
  102.     // Signaled when a value can't be coerced to the desired type. Similar
  103.     // to errOSATypeError except results from coercion.
  104.  
  105. #define errOSACantAccess                    errAENoSuchObject
  106.     // Signaled when an object is not found in a container.
  107.  
  108. #define errOSACantAssign                    -10006
  109.     // Signaled when an object cannot be set in a container.  Same as 
  110.     // AERegistry error errAEWriteDenied.
  111.  
  112. #define errOSAGeneralError                    -2700
  113.     // Signaled by user scripts or applications when no actual error code
  114.     // is to be returned.  Simply means "an error has occurred".  Most useful
  115.     // in conjunction with an error message from the application.
  116.  
  117. #define errOSADivideByZero                    -2701
  118.     // Signaled when there is an attempt to divide by zero.
  119.  
  120. #define errOSANumericOverflow                -2702
  121.     // Signaled when integer or real value is too large to be represented.
  122.  
  123. #define errOSACantLaunch                    -2703
  124.     // Signaled when application can't be launched or when it is remote and
  125.     // program linking is not enabled.
  126.  
  127. #define errOSAAppNotHighLevelEventAware        -2704
  128.     // Signaled when an application can't respond to AppleEvents.
  129.  
  130. #define errOSACorruptTerminology            -2705
  131.     // Signaled when an application's terminology resource is not readable.
  132.  
  133. #define errOSAStackOverflow                    -2706
  134.     // Signaled when the runtime stack overflows.
  135.  
  136. #define errOSAInternalTableOverflow            -2707
  137.     // Signaled when a runtime internal data structure overflows.
  138.  
  139. #define errOSADataBlockTooLarge                -2708
  140.     // Signaled when an intrinsic limitation is exceeded for the size of 
  141.     // a value or data structure.
  142.  
  143. #define errOSACantGetTerminology            -2709
  144.     // Signaled when we couldn't terminology even though it was there.
  145.  
  146. //////// Component-specific dynamic script errors:
  147. //
  148. // The range -2720 thru -2739 is reserved for component-specific runtime errors.
  149. // (Note that error codes from different scripting components in this range will
  150. // overlap.)
  151.  
  152. //////// Static errors:
  153. //
  154. // These errors comprise what are commonly thought of as parse and compile-
  155. // time errors.  However, in a dynamic system (e.g. AppleScript) any or all
  156. // of these may also occur at runtime.
  157.  
  158. #define errOSATypeError                        errAEWrongDataType
  159.     // Signaled when data was not the right type and coercion is not allowed.
  160.  
  161. #define errOSAMessageNotUnderstood            errAEEventNotHandled
  162.     // Signaled when a message was sent to an object that didn't handle it.
  163.  
  164. #define errOSAUndefinedHandler                errAEHandlerNotFound
  165.     // Signaled when a function to be returned doesn't exist.  (Probably only
  166.     // useful in languages with first-class functions that distinguish between
  167.     // functions and other values (two name spaces). This is different from
  168.     // errOSAMessageNotUnderstood, which may be signaled when the method is
  169.     // invoked.
  170.  
  171. #define errOSAIllegalAccess                    errAEAccessorNotFound
  172.     // Signaled when a container can never have the requested object.
  173.  
  174. #define errOSAIllegalIndex                    errAEIllegalIndex
  175.     // Signaled when index was out of range. Specialization of errOSACantAccess.
  176.  
  177. #define errOSAIllegalRange                    errAEImpossibleRange
  178.     // Signaled when a range is screwy. Specialization of errOSACantAccess.
  179.  
  180. #define errOSAIllegalAssign                    -10003
  181.     // Signaled when an object can never be set in a container.  Same as 
  182.     // AERegistry error errAENotModifiable.
  183.  
  184. #define errOSASyntaxError                    -2740
  185.     // Signaled when a syntax error occurs. (e.g. "Syntax error" or
  186.     // "<this> can't go after <that>").
  187.  
  188. #define errOSASyntaxTypeError                -2741
  189.     // Signaled when another form of syntax was expected. (e.g. "expected
  190.     // a <type> but found <this>").
  191.  
  192. #define errOSATokenTooLong                    -2742
  193.     // Signaled when a name or number is too long to be parsed.
  194.  
  195. #define errOSAMissingParameter                errAEDescNotFound
  196.     // Signaled when a parameter is missing for a function invocation.  Note
  197.     // that in some languages, this error may occur at runtime.
  198.  
  199. #define errOSAParameterMismatch                errAEWrongNumberArgs
  200.     // Signaled when function is called with the wrong number of parameters,
  201.     // or a parameter pattern cannot be matched.
  202.  
  203. #define errOSADuplicateParameter            -2750
  204.     // Signaled when a formal parameter, local variable, or instance variable
  205.     // is specified more than once.
  206.  
  207. #define errOSADuplicateProperty                -2751
  208.     // Signaled when a formal parameter, local variable, or instance variable
  209.     // is specified more than once.
  210.  
  211. #define errOSADuplicateHandler                -2752
  212.     // Signaled when more than one handler is defined with the same name in 
  213.     // a scope where the language doesn't allow it.
  214.  
  215. #define errOSAUndefinedVariable                -2753
  216.     // Signaled when a variable is accessed that has no value.
  217.  
  218. #define errOSAInconsistentDeclarations        -2754
  219.     // Signaled when a variable is declared inconsistently in the same scope,
  220.     // such as both local and global.
  221.  
  222. #define errOSAControlFlowError                -2755
  223.     // Signaled when illegal control flow occurs in an application (no catcher
  224.     // for throw, non-lexical loop exit, etc.).
  225.  
  226. //////// Component-specific static script errors:
  227. //
  228. // The range -2760 thru -2779 is reserved for component-specific parsing and
  229. // compile-time errors. (Note that error codes from different scripting
  230. // components in this range will overlap.)
  231.  
  232. //////// Dialect-specific script errors:
  233. //
  234. // The range -2780 thru -2799 is reserved for dialect specific error codes for
  235. // scripting components that support dialects. (Note that error codes from
  236. // different scripting components in this range will overlap, as well as error
  237. // codes from different dialects in the same scripting component.)
  238.  
  239. ////////////////////////////////////////////////////////////////////////////////
  240. // OSA Interface Descriptions
  241. ////////////////////////////////////////////////////////////////////////////////
  242. // The OSA Interface is broken down into a required interface, and several
  243. // optional interfaces to support additional functionality.  A given scripting
  244. // component may choose to support only some of the optional interfaces in
  245. // addition to the basic interface.  The OSA Component Flags may be used to 
  246. // query the Component Manager to find a scripting component with a particular
  247. // capability, or determine if a particular scripting component supports a 
  248. // particular capability.
  249. ////////////////////////////////////////////////////////////////////////////////
  250.  
  251. //////// OSA Component Flags:
  252.  
  253. #define kOSASupportsCompiling                0x0002
  254. #define kOSASupportsGetSource                0x0004
  255. #define kOSASupportsAECoercion                0x0008
  256. #define kOSASupportsAESending                0x0010
  257. #define kOSASupportsRecording                0x0020
  258. #define kOSASupportsConvenience                0x0040
  259. #define kOSASupportsDialects                0x0080
  260. #define kOSASupportsEventHandling            0x0100
  261.  
  262. //////// Component Selectors:
  263.  
  264. // Basic Scripting:
  265. #define    kOSASelectLoad                        0x0001
  266. #define    kOSASelectStore                        0x0002
  267. #define    kOSASelectExecute                    0x0003
  268. #define    kOSASelectDisplay                    0x0004
  269. #define    kOSASelectScriptError                0x0005
  270. #define    kOSASelectDispose                    0x0006
  271. #define    kOSASelectSetScriptInfo                0x0007
  272. #define    kOSASelectGetScriptInfo                0x0008
  273. #define    kOSASelectSetActiveProc                0x0009
  274. #define    kOSASelectGetActiveProc                0x000A
  275. // Compiling:
  276. #define    kOSASelectScriptingComponentName    0x0102
  277. #define    kOSASelectCompile                    0x0103
  278. #define    kOSASelectCopyID                    0x0104
  279. // GetSource:
  280. #define    kOSASelectGetSource                    0x0201
  281. // AECoercion:
  282. #define    kOSASelectCoerceFromDesc            0x0301
  283. #define kOSASelectCoerceToDesc                0x0302
  284. // AESending:
  285. #define    kOSASelectSetSendProc                0x0401
  286. #define    kOSASelectGetSendProc                0x0402
  287. #define    kOSASelectSetCreateProc                0x0403
  288. #define    kOSASelectGetCreateProc                0x0404
  289. #define kOSASelectSetDefaultTarget            0x0405
  290. // Recording:
  291. #define    kOSASelectStartRecording            0x0501
  292. #define    kOSASelectStopRecording                0x0502
  293. // Convenience:
  294. #define    kOSASelectLoadExecute                0x0601
  295. #define    kOSASelectCompileExecute            0x0602
  296. #define    kOSASelectDoScript                    0x0603
  297. // Dialects:
  298. #define kOSASelectSetCurrentDialect            0x0701
  299. #define kOSASelectGetCurrentDialect            0x0702
  300. #define kOSASelectAvailableDialects            0x0703
  301. #define kOSASelectGetDialectInfo            0x0704
  302. #define kOSASelectAvailableDialectCodeList    0x0705
  303. // Event Handling:
  304. #define    kOSASelectSetResumeDispatchProc        0x0801
  305. #define    kOSASelectGetResumeDispatchProc        0x0802
  306. #define    kOSASelectExecuteEvent                0x0803
  307. #define    kOSASelectDoEvent                    0x0804
  308. #define    kOSASelectMakeContext                0x0805
  309.  
  310. #define    kOSASelectComponentSpecificStart    0x1001
  311.     // scripting component specific selectors are added beginning with this
  312.     // value
  313.  
  314. //////// Mode Flags:
  315. //
  316. // Warning: These should not conflict with the AESend mode flags in
  317. // AppleEvents.h, because we may want to use them as OSA mode flags too.
  318.  
  319. #define kOSAModePreventGetSource            0x00000001
  320.     // This mode flag may be passed to OSALoad, OSAStore or OSACompile to
  321.     // instruct the scripting component to not retain the "source" of an
  322.     // expression.  This will cause the OSAGetSource call to return the error
  323.     // errOSASourceNotAvailable if used.  However, some scripting components
  324.     // may not retain the source anyway.  This is mainly used when either space
  325.     // efficiency is desired, or a script is to be "locked" so that its
  326.     // implementation may not be viewed.
  327.  
  328. #define kOSAModeNeverInteract                kAENeverInteract
  329. #define kOSAModeCanInteract                    kAECanInteract
  330. #define kOSAModeAlwaysInteract                kAEAlwaysInteract
  331. #define kOSAModeDontReconnect                kAEDontReconnect
  332.     // These mode flags may be passed to OSACompile, OSAExecute, OSALoadExecute
  333.     // OSACompileExecute, OSADoScript, OSAExecuteEvent, or OSADoEvent to
  334.     // indicate whether or not the script may interact with the user, switch
  335.     // layer or reconnect if necessary.  Any AppleEvents will be sent with the
  336.     // corresponding AESend mode supplied.
  337.  
  338. #define kOSAModeCantSwitchLayer                0x00000040
  339.     // This mode flag may be passed to OSACompile, OSAExecute, OSALoadExecute
  340.     // OSACompileExecute, OSADoScript, OSAExecuteEvent, or OSADoEvent to
  341.     // indicate whether or not AppleEvents should be sent with the
  342.     // kAECanSwitchLayer mode flag sent or not. NOTE: This flag is exactly the
  343.     // opposite sense of the AppleEvent flag kAECanSwitchLayer.  This is to
  344.     // provide a more convenient default, i.e. not supplying any mode
  345.     // (kOSAModeNull) means to send events with kAECanSwitchLayer.  Supplying
  346.     // the kOSAModeCantSwitchLayer mode flag will cause AESend to be called
  347.     // without kAECanSwitchLayer.
  348.  
  349. #define kOSAModeDoRecord                    0x00001000
  350.     // This mode flag may be passed to OSACompile, OSAExecute, OSALoadExecute
  351.     // OSACompileExecute, OSADoScript, OSAExecuteEvent, or OSADoEvent to
  352.     // indicate whether or not AppleEvents should be sent with the kAEDontRecord
  353.     // mode flag sent or not. NOTE: This flag is exactly the opposite sense of
  354.     // the AppleEvent flag kAEDontRecord.  This is to provide a more convenient
  355.     // default, i.e. not supplying any mode (kOSAModeNull) means to send events
  356.     // with kAEDontRecord.  Supplying the kOSAModeDoRecord mode flag will 
  357.     // cause AESend to be called without kAEDontRecord.
  358.  
  359. #define kOSAModeCompileIntoContext            0x00000002
  360.     // This is a mode flag for OSACompile that indicates that a context should
  361.     // be created as the result of compilation. All handler definitions are
  362.     // inserted into the new context, and variables are initialized by
  363.     // evaluating their initial values in a null context (i.e. they must be
  364.     // constant expressions).
  365.  
  366. #define kOSAModeAugmentContext                0x00000004
  367.     // This is a mode flag for OSACompile that indicates that the previous
  368.     // script ID (input to OSACompile) should be augmented with any new
  369.     // definitions in the sourceData rather than replaced with a new script.
  370.     // This means that the previous script ID must designate a context.
  371.     // The presence of this flag causes the kOSAModeCompileIntoContext flag
  372.     // to be implicitly used, causing any new definitions to be initialized
  373.     // in a null context.
  374.  
  375. #define kOSAModeDisplayForHumans            0x00000008
  376.     // This mode flag may be passed to OSADisplay or OSADoScript to indicate
  377.     // that output only need be human-readable, not re-compilable by OSACompile.
  378.     // If used, output may be arbitrarily "beautified", e.g. quotes may be left
  379.     // off of string values, long lists may have elipses, etc.
  380.  
  381. #define kOSAModeDontStoreParent                0x00004000
  382.     // This mode flag may be passed to OSAStore in the case where the scriptID
  383.     // is a context.  This causes the context to be saved, but not the context's
  384.     // parent context.  When the stored context is loaded back in, the parent
  385.     // will be kOSANullScript.
  386.  
  387. ////////////////////////////////////////////////////////////////////////////////
  388. // OSA Basic Scripting Interface
  389. ////////////////////////////////////////////////////////////////////////////////
  390. // Scripting components must at least support the Basic Scripting interface.
  391. ////////////////////////////////////////////////////////////////////////////////
  392.  
  393. //////// Loading and Storing Scripts:
  394. //
  395. // These routines allow scripts to be loaded and stored in their internal
  396. // (possibly compiled, non-text) representation.
  397.  
  398. #define kOSAScriptResourceType                kOSAGenericScriptingComponentSubtype
  399.     // Resource type for scripts.
  400.     
  401. #define typeOSAGenericStorage                kOSAScriptResourceType
  402.     // Default type given to OSAStore which creates "generic" loadable script
  403.     // data descriptors.
  404.  
  405. pascal OSAError
  406. OSALoad(ComponentInstance        scriptingComponent,
  407.         const AEDesc*            scriptData,
  408.         long                    modeFlags,
  409.         OSAID*                    resultingScriptID)
  410.     OSAComponentFunctionInline(kOSASelectLoad, 12);
  411.     //
  412.     // Errors:
  413.     //    badComponentInstance    invalid scripting component instance
  414.     //     errOSASystemError
  415.     //     errOSABadStorageType:    scriptData not for this scripting component
  416.     //     errOSACorruptData:        data seems to be corrupt
  417.     //     errOSADataFormatObsolete    script data format is no longer supported
  418.     //     errOSADataFormatTooNew        script data format is from a newer version
  419.     // 
  420.     // ModeFlags:
  421.     //    kOSAModePreventGetSource
  422.  
  423. pascal OSAError
  424. OSAStore(ComponentInstance        scriptingComponent, 
  425.          OSAID                    scriptID, 
  426.          DescType                desiredType,
  427.          long                    modeFlags,
  428.          AEDesc*                resultingScriptData)
  429.     OSAComponentFunctionInline(kOSASelectStore, 16);
  430.     //
  431.     // Errors:
  432.     //    badComponentInstance    invalid scripting component instance
  433.     //     errOSASystemError
  434.     //     errOSAInvalidID
  435.     //     errOSABadStorageType:    desiredType not for this scripting component
  436.     // 
  437.     // ModeFlags:
  438.     //    kOSAModePreventGetSource
  439.     //    kOSAModeDontStoreParent
  440.  
  441. //////// Executing Scripts:
  442.  
  443. pascal OSAError
  444. OSAExecute(ComponentInstance    scriptingComponent,
  445.            OSAID                compiledScriptID,
  446.            OSAID                contextID,
  447.            long                    modeFlags,
  448.            OSAID*                resultingScriptValueID)
  449.     OSAComponentFunctionInline(kOSASelectExecute, 16);
  450.     // This call runs a script.  The contextID represents the environment
  451.     // with which global variables in the script are resolved.  The constant
  452.     // kOSANullScript may be used for the contextID if the application wishes
  453.     // to not deal with context directly (a default one is associated with each
  454.     // scripting component instance).  The resultingScriptValueID is the 
  455.     // result of evaluation, and contains a value which may be displayed using
  456.     // the OSAGetSource call.  The modeFlags convey scripting component
  457.     // specific information.
  458.     //
  459.     // Errors:
  460.     //    badComponentInstance    invalid scripting component instance
  461.     //     errOSASystemError
  462.     //     errOSAInvalidID
  463.     //     errOSAScriptError:        the executing script got an error
  464.     //
  465.     // ModeFlags:
  466.     //    kOSAModeNeverInteract
  467.     //    kOSAModeCanInteract
  468.     //    kOSAModeAlwaysInteract
  469.     //    kOSAModeCantSwitchLayer
  470.     //    kOSAModeDontReconnect
  471.     //    kOSAModeDoRecord
  472.  
  473. //////// Displaying results:
  474.  
  475. pascal OSAError
  476. OSADisplay(ComponentInstance    scriptingComponent,
  477.            OSAID                scriptValueID,
  478.            DescType                desiredType,
  479.            long                    modeFlags,
  480.            AEDesc*                resultingText)
  481.     OSAComponentFunctionInline(kOSASelectDisplay, 16);
  482.     // This call is used to convert results (script value IDs) into displayable
  483.     // text. The desiredType should be at least typeChar, and modeFlags are
  484.     // scripting system specific flags to control the formatting of the
  485.     // resulting text. This call differs from OSAGetSource in that (1) it
  486.     // always produces at least typeChar, (2) is only works on script values,
  487.     // (3) it may display it's output in non-compilable form (e.g. without
  488.     // string quotes, elipses inserted in long and/or circular lists, etc.) and
  489.     // (4) it is required by the basic scripting interface.
  490.     //
  491.     // Errors:
  492.     //    badComponentInstance    invalid scripting component instance
  493.     //     errOSASystemError
  494.     //     errOSAInvalidID
  495.     //     errAECoercionFail:        desiredType not supported by scripting component
  496.     //
  497.     // ModeFlags:
  498.     //    kOSAModeDisplayForHumans
  499.  
  500. //////// Getting Error Information:
  501.  
  502. pascal OSAError
  503. OSAScriptError(ComponentInstance    scriptingComponent,
  504.                OSType                selector,
  505.                DescType                desiredType,
  506.                AEDesc*                resultingErrorDescription)
  507.     OSAComponentFunctionInline(kOSASelectScriptError, 12);
  508.     // Whenever script execution returns errOSAExecutionError, this routine
  509.     // may be used to get information about that error.  The selector describes
  510.     // the type of information desired about the error (various selectors are
  511.     // listed below).  The desiredType indicates the data type of the result
  512.     // desired for that selector.
  513.     //
  514.     // Errors:
  515.     //    badComponentInstance    invalid scripting component instance
  516.     //     errOSASystemError
  517.     //    errOSABadSelector:        selector not supported by scripting component
  518.     //     errAECoercionFail:        desiredType not supported by scripting component
  519.  
  520. // OSAScriptError selectors:
  521.  
  522. #define kOSAErrorNumber                        keyErrorNumber
  523.     // This selector is used to determine the error number of a script error.
  524.     // These error numbers may be either system error numbers, or error numbers
  525.     // that are scripting component specific.
  526.     // Required desiredTypes:
  527.     //    typeShortInteger
  528.  
  529. #define kOSAErrorMessage                    keyErrorString
  530.     // This selector is used to determine the full error message associated
  531.     // with the error number.  It should include the name of the application
  532.     // which caused the error, as well as the specific error that occurred.
  533.     // This selector is sufficient for simple error reporting (but see
  534.     // kOSAErrorBriefMessage, below).
  535.     // Required desiredTypes:
  536.     //    typeChar                    error message string
  537.  
  538. #define kOSAErrorBriefMessage                'errb'
  539.     // This selector is used to determine a brief error message associated with
  540.     // the error number.  This message and should not mention the name of the
  541.     // application which caused the error, any partial results or offending
  542.     // object (see kOSAErrorApp, kOSAErrorPartialResult and
  543.     // kOSAErrorOffendingObject, below).
  544.     // Required desiredTypes:
  545.     //    typeChar                    brief error message string
  546.  
  547. #define kOSAErrorApp                        'erap'
  548.     // This selector is used to determine which application actually got the
  549.     // error (if it was the result of an AESend), or the current application
  550.     // if ....
  551.     // Required desiredTypes:
  552.     //    typeProcessSerialNumber        PSN of the errant application
  553.     //    typeChar                    name of the errant application
  554.  
  555. #define kOSAErrorPartialResult                'ptlr'
  556.     // This selector is used to determine any partial result returned by an 
  557.     // operation. If an AESend call failed, but a partial result was returned,
  558.     // then the partial result may be returned as an AEDesc.
  559.     // Required desiredTypes:
  560.     //    typeBest                    AEDesc of any partial result
  561.  
  562. #define kOSAErrorOffendingObject            'erob'
  563.     // This selector is used to determine any object which caused the error
  564.     // that may have been indicated by an application.  The result is an 
  565.     // AEDesc.
  566.     // Required desiredTypes:
  567.     //    typeBest                    AEDesc of any offending object
  568.     
  569. #define kOSAErrorExpectedType                'errt'
  570.     // This selector is used to determine the type expected by a coercion 
  571.     // operation if a type error occurred. 
  572.  
  573. #define kOSAErrorRange                        'erng'
  574.     // This selector is used to determine the source text range (start and 
  575.     // end positions) of where the error occurred.
  576.     // Required desiredTypes:
  577.     //    typeOSAErrorRange
  578.  
  579. #define typeOSAErrorRange                    'erng'
  580.     // An AERecord type containing keyOSASourceStart and keyOSASourceEnd fields
  581.     // of type short.
  582. #define keyOSASourceStart                    'srcs'
  583.     // Field of a typeOSAErrorRange record of typeShortInteger.
  584. #define keyOSASourceEnd                        'srce'
  585.     // Field of a typeOSAErrorRange record of typeShortInteger.
  586.  
  587. //////// Disposing Script IDs:
  588.  
  589. pascal OSAError
  590. OSADispose(ComponentInstance    scriptingComponent,
  591.            OSAID                scriptID)
  592.     OSAComponentFunctionInline(kOSASelectDispose, 4);
  593.     // Disposes a script or context.
  594.     //
  595.     // Errors:
  596.     //    badComponentInstance    invalid scripting component instance
  597.     //     errOSASystemError
  598.     //     errOSAInvalidID
  599.  
  600. //////// Getting and Setting Script Information:
  601.  
  602. pascal OSAError
  603. OSASetScriptInfo(ComponentInstance        scriptingComponent,
  604.                  OSAID                    scriptID,
  605.                  OSType                    selector,
  606.                  long                    value)
  607.     OSAComponentFunctionInline(kOSASelectSetScriptInfo, 12);
  608.     //
  609.     // Errors:
  610.     //    badComponentInstance    invalid scripting component instance
  611.     //     errOSASystemError
  612.     //     errOSAInvalidID
  613.     //    errOSABadSelector:        selector not supported by scripting component
  614.     //                             or selector not for this scriptID
  615.  
  616. pascal OSAError
  617. OSAGetScriptInfo(ComponentInstance        scriptingComponent,
  618.                  OSAID                    scriptID,
  619.                  OSType                    selector,
  620.                  long*                    result)
  621.     OSAComponentFunctionInline(kOSASelectGetScriptInfo, 12);
  622.     //
  623.     // Errors:
  624.     //    badComponentInstance    invalid scripting component instance
  625.     //     errOSASystemError
  626.     //     errOSAInvalidID
  627.     //    errOSABadSelector:        selector not supported by scripting component
  628.     //                             or selector not for this scriptID
  629.  
  630. #define kOSAScriptIsModified            'modi'
  631.     // Selector returns boolean.
  632.  
  633. #define kOSAScriptIsTypeCompiledScript    'cscr'
  634.     // Selector returns boolean.
  635.     
  636. #define kOSAScriptIsTypeScriptValue        'valu'
  637.     // Selector returns boolean.
  638.  
  639. #define kOSAScriptIsTypeScriptContext    'cntx'
  640.     // Selector returns boolean.
  641.  
  642. #define kOSAScriptBestType                'best'
  643.     // Selector returns a DescType which may be passed to OSACoerceToDesc.
  644.  
  645. #define kOSACanGetSource                'gsrc'
  646.     // This selector is used to determine whether a script has source 
  647.     // associated with it that when given to OSAGetSource, the call will not
  648.     // fail.  The selector returns a boolean.
  649.  
  650. //////// Manipulating the ActiveProc:
  651. //
  652. // Scripting systems will supply default values for these procedures if they
  653. // are not set by the client:
  654.  
  655. typedef pascal OSErr (*OSAActiveProcPtr)(long refCon);
  656.  
  657. pascal OSAError
  658. OSASetActiveProc(ComponentInstance        scriptingComponent,
  659.                  OSAActiveProcPtr        activeProc,
  660.                  long                    refCon)
  661.     OSAComponentFunctionInline(kOSASelectSetActiveProc, 8);
  662.     // If activeProc is nil, the default activeProc is used.
  663.     //
  664.     // Errors:
  665.     //    badComponentInstance    invalid scripting component instance
  666.     //     errOSASystemError
  667.  
  668. pascal OSAError
  669. OSAGetActiveProc(ComponentInstance        scriptingComponent,
  670.                  OSAActiveProcPtr*        activeProc,
  671.                  long*                    refCon)
  672.     OSAComponentFunctionInline(kOSASelectGetActiveProc, 8);
  673.     //
  674.     // Errors:
  675.     //    badComponentInstance    invalid scripting component instance
  676.     //     errOSASystemError
  677.  
  678. ////////////////////////////////////////////////////////////////////////////////
  679. // OSA Optional Compiling Interface
  680. ////////////////////////////////////////////////////////////////////////////////
  681. // Scripting components that support the Compiling interface have the 
  682. // kOSASupportsCompiling bit set in it's ComponentDescription.
  683. ////////////////////////////////////////////////////////////////////////////////
  684.  
  685. pascal OSAError
  686. OSAScriptingComponentName(ComponentInstance    scriptingComponent,
  687.                           AEDesc*            resultingScriptingComponentName)
  688.     OSAComponentFunctionInline(kOSASelectScriptingComponentName, 4);
  689.     // Given a scripting component, this routine returns the name of that
  690.     // scripting component in a type that is coercable to text (typeChar).
  691.     // The generic scripting component returns the name of the default
  692.     // scripting component.  This name should be sufficient to convey to the
  693.     // user the kind of script (syntax) he is expected to write.
  694.     //
  695.     // Errors:
  696.     //    badComponentInstance    invalid scripting component instance
  697.     //     errOSASystemError
  698.  
  699. pascal OSAError
  700. OSACompile(ComponentInstance    scriptingComponent,
  701.            const AEDesc*        sourceData,
  702.            long                    modeFlags,
  703.            OSAID*                previousAndResultingScriptID)
  704.     OSAComponentFunctionInline(kOSASelectCompile, 12);
  705.     // Coerces input desc (possibly text) into a script's internal format.
  706.     // Once compiled, the script is ready to run.  The modeFlags convey
  707.     // scripting component specific information.  The previous script ID
  708.     // (result parameter) is made to refer to the newly compiled script,
  709.     // unless it was originally kOSANullScript.  In this case a new script
  710.     // ID is created and used.
  711.     //
  712.     // Errors:
  713.     //    badComponentInstance    invalid scripting component instance
  714.     //     errOSASystemError
  715.     //    errAECoercionFail:        sourceData is not compilable
  716.     //     errOSAScriptError:        sourceData was a bad script (syntax error)
  717.     //     errOSAInvalidID:        previousAndResultingCompiledScriptID was not
  718.     //                            valid on input
  719.     //
  720.     // ModeFlags:
  721.     //    kOSAModePreventGetSource
  722.     //    kOSAModeCompileIntoContext
  723.     //    kOSAModeAugmentContext
  724.     //    kOSAModeNeverInteract
  725.     //    kOSAModeCanInteract
  726.     //    kOSAModeAlwaysInteract
  727.     //    kOSAModeCantSwitchLayer
  728.     //    kOSAModeDontReconnect
  729.     //    kOSAModeDoRecord
  730.  
  731. pascal OSAError
  732. OSACopyID(ComponentInstance        scriptingComponent,
  733.           OSAID                    fromID,
  734.           OSAID*                toID)
  735.     OSAComponentFunctionInline(kOSASelectCopyID, 8);
  736.     // If toID is a reference to kOSANullScript then it is updated to have a
  737.     // new scriptID value.  This call can be used to perform undo or revert
  738.     // operations on scripts. 
  739.     //
  740.     // Errors:
  741.     //    badComponentInstance    invalid scripting component instance
  742.     //     errOSASystemError
  743.     //     errOSAInvalidID
  744.  
  745. ////////////////////////////////////////////////////////////////////////////////
  746. // OSA Optional GetSource Interface
  747. ////////////////////////////////////////////////////////////////////////////////
  748. // Scripting components that support the GetSource interface have the 
  749. // kOSASupportsGetSource bit set in it's ComponentDescription.
  750. ////////////////////////////////////////////////////////////////////////////////
  751.  
  752. pascal OSAError
  753. OSAGetSource(ComponentInstance        scriptingComponent,
  754.              OSAID                    scriptID,
  755.              DescType                desiredType,
  756.              AEDesc*                resultingSourceData)
  757.     OSAComponentFunctionInline(kOSASelectGetSource, 12);
  758.     // This routine causes a compiled script to be output in a form (possibly
  759.     // text) such that it is suitable to be passed back to OSACompile.
  760.     //
  761.     // Errors:
  762.     //    badComponentInstance    invalid scripting component instance
  763.     //     errOSASystemError
  764.     //     errOSAInvalidID
  765.     //    errOSASourceNotAvailable    can't get source for this scriptID
  766.  
  767. ////////////////////////////////////////////////////////////////////////////////
  768. // OSA Optional AECoercion Interface
  769. ////////////////////////////////////////////////////////////////////////////////
  770. // Scripting components that support the AECoercion interface have the 
  771. // kOSASupportsAECoercion bit set in it's ComponentDescription.
  772. ////////////////////////////////////////////////////////////////////////////////
  773.  
  774. pascal OSAError
  775. OSACoerceFromDesc(ComponentInstance        scriptingComponent,
  776.                   const AEDesc*            scriptData,
  777.                   long                    modeFlags,
  778.                   OSAID*                resultingScriptID)
  779.     OSAComponentFunctionInline(kOSASelectCoerceFromDesc, 12);
  780.     // This routine causes script data to be coerced into a script value.
  781.     // If the scriptData is an AppleEvent, then the resultingScriptID is a
  782.     // compiled script ID (mode flags for OSACompile may be used in this case).
  783.     // Other scriptData descriptors create script value IDs.
  784.     //
  785.     // Errors:
  786.     //    badComponentInstance    invalid scripting component instance
  787.     //     errOSASystemError
  788.     //
  789.     // ModeFlags:
  790.     //    kOSAModePreventGetSource
  791.     //    kOSAModeCompileIntoContext
  792.     //    kOSAModeNeverInteract
  793.     //    kOSAModeCanInteract
  794.     //    kOSAModeAlwaysInteract
  795.     //    kOSAModeCantSwitchLayer
  796.     //    kOSAModeDontReconnect
  797.     //    kOSAModeDoRecord
  798.  
  799. pascal OSAError
  800. OSACoerceToDesc(ComponentInstance        scriptingComponent,
  801.                 OSAID                    scriptID,
  802.                 DescType                desiredType,
  803.                 long                    modeFlags,
  804.                 AEDesc*                    result)
  805.     OSAComponentFunctionInline(kOSASelectCoerceToDesc, 16);
  806.     // This routine causes a script value to be coerced into any desired form.
  807.     // If the scriptID denotes a compiled script, then it may be coerced to 
  808.     // typeAppleEvent.
  809.     //
  810.     // Errors:
  811.     //    badComponentInstance    invalid scripting component instance
  812.     //     errOSASystemError
  813.     //     errOSAInvalidID
  814.  
  815. ////////////////////////////////////////////////////////////////////////////////
  816. // OSA Optional AESending Interface
  817. ////////////////////////////////////////////////////////////////////////////////
  818. // Scripting components that support the AESending interface have the 
  819. // kOSASupportsAESending bit set in it's ComponentDescription.
  820. ////////////////////////////////////////////////////////////////////////////////
  821.  
  822. // Scripting systems will supply default values for these procedures if they
  823. // are not set by the client:
  824.  
  825. typedef pascal OSErr (*AESendProcPtr)(const AppleEvent*        theAppleEvent,
  826.                                       AppleEvent*            reply,
  827.                                       AESendMode             sendMode,
  828.                                       AESendPriority         sendPriority,
  829.                                       long                     timeOutInTicks,
  830.                                       IdleProcPtr            idleProc,
  831.                                       EventFilterProcPtr    filterProc,
  832.                                       long                     refCon);
  833.  
  834. pascal OSAError
  835. OSASetSendProc(ComponentInstance    scriptingComponent,
  836.                AESendProcPtr        sendProc,
  837.                long                    refCon)
  838.     OSAComponentFunctionInline(kOSASelectSetSendProc, 8);
  839.     // If sendProc is nil, the default sendProc is used.
  840.     //
  841.     // Errors:
  842.     //    badComponentInstance    invalid scripting component instance
  843.     //     errOSASystemError
  844.  
  845. pascal OSAError
  846. OSAGetSendProc(ComponentInstance    scriptingComponent,
  847.                AESendProcPtr*        sendProc,
  848.                long*                refCon)
  849.     OSAComponentFunctionInline(kOSASelectGetSendProc, 8);
  850.     //
  851.     // Errors:
  852.     //    badComponentInstance    invalid scripting component instance
  853.     //     errOSASystemError
  854.  
  855. typedef pascal OSErr (*AECreateAppleEventProcPtr)(
  856.                         AEEventClass             theAEEventClass,
  857.                         AEEventID                 theAEEventID,
  858.                         const AEAddressDesc*    target,
  859.                         short                     returnID,
  860.                         long                     transactionID,
  861.                         AppleEvent*                result,
  862.                         long                     refCon);
  863.  
  864. pascal OSAError
  865. OSASetCreateProc(ComponentInstance            scriptingComponent,
  866.                  AECreateAppleEventProcPtr    createProc,
  867.                  long                        refCon)
  868.     OSAComponentFunctionInline(kOSASelectSetCreateProc, 8);
  869.     // If createProc is nil, the default createProc is used.
  870.     //
  871.     // Errors:
  872.     //    badComponentInstance    invalid scripting component instance
  873.     //     errOSASystemError
  874.  
  875. pascal OSAError
  876. OSAGetCreateProc(ComponentInstance            scriptingComponent,
  877.                  AECreateAppleEventProcPtr*    createProc,
  878.                  long*                        refCon)
  879.     OSAComponentFunctionInline(kOSASelectGetCreateProc, 8);
  880.     //
  881.     // Errors:
  882.     //    badComponentInstance    invalid scripting component instance
  883.     //     errOSASystemError
  884.  
  885. pascal OSAError
  886. OSASetDefaultTarget(ComponentInstance        scriptingComponent,
  887.                      const AEAddressDesc*    target)
  888.     OSAComponentFunctionInline(kOSASelectSetDefaultTarget, 4);
  889.     // This routine sets the default target application for AE sending.
  890.     // It also establishes the default target from which terminologies come.
  891.     // It is effectively like having an AppleScript "tell" statement around
  892.     // the entire program.  If this routine is not called, or if the target 
  893.     // is a null AEDesc, then the current application is the default target.
  894.     //
  895.     // Errors:
  896.     //    badComponentInstance    invalid scripting component instance
  897.     //     errOSASystemError
  898.  
  899. ////////////////////////////////////////////////////////////////////////////////
  900. // OSA Optional Recording Interface
  901. ////////////////////////////////////////////////////////////////////////////////
  902. // Scripting components that support the Recording interface have the 
  903. // kOSASupportsRecording bit set in it's ComponentDescription.
  904. ////////////////////////////////////////////////////////////////////////////////
  905.  
  906. pascal OSAError
  907. OSAStartRecording(ComponentInstance        scriptingComponent,
  908.                   OSAID*                compiledScriptToModifyID)
  909.     OSAComponentFunctionInline(kOSASelectStartRecording, 4);
  910.     // Starts recording.  If compiledScriptToModifyID is kOSANullScript, a
  911.     // new script ID is created and returned.  If the current application has
  912.     // a handler for the kOSARecordedText event, then kOSARecordedText events
  913.     // are sent to the application containing the text of each AppleEvent 
  914.     // recorded.
  915.     //
  916.     // Errors:
  917.     //    badComponentInstance    invalid scripting component instance
  918.     //     errOSASystemError
  919.     //     errOSAInvalidID
  920.     //    errOSARecordingIsAlreadyOn
  921.  
  922. pascal OSAError
  923. OSAStopRecording(ComponentInstance    scriptingComponent,
  924.                  OSAID                compiledScriptID)
  925.     OSAComponentFunctionInline(kOSASelectStopRecording, 4);
  926.     // If compiledScriptID is not being recorded into or recording is not
  927.     // currently on, no error is returned.
  928.     //
  929.     // Errors:
  930.     //    badComponentInstance    invalid scripting component instance
  931.     //     errOSASystemError
  932.     //     errOSAInvalidID
  933.  
  934. ////////////////////////////////////////////////////////////////////////////////
  935. // OSA Optional Convenience Interface
  936. ////////////////////////////////////////////////////////////////////////////////
  937. // Scripting components that support the Convenience interface have the 
  938. // kOSASupportsConvenience bit set in it's ComponentDescription.
  939. ////////////////////////////////////////////////////////////////////////////////
  940.  
  941. pascal OSAError 
  942. OSALoadExecute(ComponentInstance    scriptingComponent,
  943.                const AEDesc*        scriptData,
  944.                OSAID                contextID,
  945.                long                    modeFlags,
  946.                OSAID*                resultingScriptValueID)
  947.     OSAComponentFunctionInline(kOSASelectLoadExecute, 16);
  948.     // This routine is effectively equivalent to calling OSALoad followed by
  949.     // OSAExecute.  After execution, the compiled source is disposed.  Only the
  950.     // resulting value ID is retained.
  951.     //
  952.     // Errors:
  953.     //    badComponentInstance    invalid scripting component instance
  954.     //     errOSASystemError
  955.     //     errOSABadStorageType:    scriptData not for this scripting component
  956.     //     errOSACorruptData:        data seems to be corrupt
  957.     //     errOSADataFormatObsolete    script data format is no longer supported
  958.     //     errOSADataFormatTooNew        script data format is from a newer version
  959.     //     errOSAInvalidID
  960.     //     errOSAScriptError:        the executing script got an error
  961.     //
  962.     // ModeFlags:
  963.     //    kOSAModeNeverInteract
  964.     //    kOSAModeCanInteract
  965.     //    kOSAModeAlwaysInteract
  966.     //    kOSAModeCantSwitchLayer
  967.     //    kOSAModeDontReconnect
  968.     //    kOSAModeDoRecord
  969.  
  970. pascal OSAError 
  971. OSACompileExecute(ComponentInstance    scriptingComponent,
  972.                   const AEDesc*        sourceData,
  973.                   OSAID                contextID,
  974.                   long                modeFlags,
  975.                   OSAID*            resultingScriptValueID)
  976.     OSAComponentFunctionInline(kOSASelectCompileExecute, 16);
  977.     // This routine is effectively equivalent to calling OSACompile followed by
  978.     // OSAExecute.  After execution, the compiled source is disposed.  Only the
  979.     // resulting value ID is retained.
  980.     //
  981.     // Errors:
  982.     //    badComponentInstance    invalid scripting component instance
  983.     //     errOSASystemError
  984.     //    errAECoercionFail:        sourceData is not compilable
  985.     //     errOSAScriptError:        sourceData was a bad script (syntax error)
  986.     //     errOSAInvalidID:        previousAndResultingCompiledScriptID was not
  987.     //                            valid on input
  988.     //     errOSAScriptError:        the executing script got an error
  989.     //
  990.     // ModeFlags:
  991.     //    kOSAModeNeverInteract
  992.     //    kOSAModeCanInteract
  993.     //    kOSAModeAlwaysInteract
  994.     //    kOSAModeCantSwitchLayer
  995.     //    kOSAModeDontReconnect
  996.     //    kOSAModeDoRecord
  997.  
  998. pascal OSAError 
  999. OSADoScript(ComponentInstance    scriptingComponent,
  1000.             const AEDesc*        sourceData,
  1001.             OSAID                contextID,
  1002.             DescType            desiredType,
  1003.             long                modeFlags,
  1004.             AEDesc*                resultingText)
  1005.     OSAComponentFunctionInline(kOSASelectDoScript, 20);
  1006.     // This routine is effectively equivalent to calling OSACompile followed by
  1007.     // OSAExecute and then OSADisplay.  After execution, the compiled source
  1008.     // and the resulting value are is disposed.  Only the resultingText
  1009.     // descriptor is retained.  If a script error occur during processing, the 
  1010.     // resultingText gets the error message of the error, and errOSAScriptError
  1011.     // is returned.  OSAScriptError may still be used to extract more 
  1012.     // information about the particular error.
  1013.     //
  1014.     // Errors:
  1015.     //    badComponentInstance    invalid scripting component instance
  1016.     //     errOSASystemError
  1017.     //    errAECoercionFail:        sourceData is not compilable or 
  1018.     //                            desiredType not supported by scripting component
  1019.     //     errOSAScriptError:        sourceData was a bad script (syntax error)
  1020.     //     errOSAInvalidID:        previousAndResultingCompiledScriptID was not
  1021.     //                            valid on input
  1022.     //     errOSAScriptError:        the executing script got an error
  1023.     //
  1024.     // ModeFlags:
  1025.     //    kOSAModeNeverInteract
  1026.     //    kOSAModeCanInteract
  1027.     //    kOSAModeAlwaysInteract
  1028.     //    kOSAModeCantSwitchLayer
  1029.     //    kOSAModeDontReconnect
  1030.     //    kOSAModeDoRecord
  1031.     //    kOSAModeDisplayForHumans
  1032.  
  1033. ////////////////////////////////////////////////////////////////////////////////
  1034. // OSA Optional Dialects Interface
  1035. ////////////////////////////////////////////////////////////////////////////////
  1036. // Scripting components that support the Dialects interface have the 
  1037. // kOSASupportsDialects bit set in it's ComponentDescription.
  1038. ////////////////////////////////////////////////////////////////////////////////
  1039.  
  1040. // These calls allows an scripting component that supports different dialects
  1041. // to dynamically switch between those dialects.  Although this interface is
  1042. // specified, the particular dialect codes are scripting component dependent.
  1043.  
  1044. pascal OSAError 
  1045. OSASetCurrentDialect(ComponentInstance    scriptingComponent,
  1046.                      short                dialectCode)
  1047.     OSAComponentFunctionInline(kOSASelectSetCurrentDialect, 2);
  1048.     //
  1049.     // Errors:
  1050.     //    badComponentInstance    invalid scripting component instance
  1051.     //     errOSASystemError
  1052.     //     errOSANoSuchDialect:    invalid dialectCode
  1053.  
  1054. pascal OSAError 
  1055. OSAGetCurrentDialect(ComponentInstance    scriptingComponent,
  1056.                      short*                resultingDialectCode)
  1057.     OSAComponentFunctionInline(kOSASelectGetCurrentDialect, 4);
  1058.     //
  1059.     // Errors:
  1060.     //    badComponentInstance    invalid scripting component instance
  1061.     //     errOSASystemError
  1062.  
  1063. pascal OSAError 
  1064. OSAAvailableDialects(ComponentInstance    scriptingComponent,
  1065.                      AEDesc*            resultingDialectInfoList)
  1066.     OSAComponentFunctionInline(kOSASelectAvailableDialects, 4);
  1067.     // This call return an AEList containing information about each of the
  1068.     // currently available dialects of a scripting component.  Each item
  1069.     // is an AERecord of typeOSADialectInfo that contains at least the fields
  1070.     // keyOSADialectName, keyOSADialectCode, KeyOSADialectLangCode and 
  1071.     // keyOSADialectScriptCode.
  1072.     //
  1073.     // Errors:
  1074.     //    badComponentInstance    invalid scripting component instance
  1075.     //     errOSASystemError
  1076.  
  1077. pascal OSAError
  1078. OSAGetDialectInfo(ComponentInstance        scriptingComponent,
  1079.                   short                    dialectCode,
  1080.                   OSType                selector,
  1081.                   AEDesc*                resultingDialectInfo)
  1082.     OSAComponentFunctionInline(kOSASelectGetDialectInfo, 10);
  1083.     // This call gives information about the specified dialect of a scripting
  1084.     // component. It returns an AEDesc whose type depends on the selector 
  1085.     // specified. Available selectors are the same as the field keys for a
  1086.     // dialect info record. The type of AEDesc returned is the same as the 
  1087.     // type of the field that has same key as the selector.
  1088.     //
  1089.     // Errors:
  1090.     //    badComponentInstance    invalid scripting component instance
  1091.     //     errOSASystemError
  1092.     //  errOSABadSelector
  1093.     //     errOSANoSuchDialect:    invalid dialectCode
  1094.  
  1095. pascal OSAError 
  1096. OSAAvailableDialectCodeList(ComponentInstance    scriptingComponent,
  1097.                              AEDesc*                resultingDialectCodeList)
  1098.     OSAComponentFunctionInline(kOSASelectAvailableDialectCodeList, 4);
  1099.     // This is alternative to OSAGetAvailableDialectCodeList. Use this call
  1100.     // and  OSAGetDialectInfo to get information on dialects.
  1101.     // This call return an AEList containing dialect code for each of the
  1102.     // currently available dialects of a scripting component. Each dialect
  1103.     // code is a short integer of type typeShortInteger.
  1104.     //
  1105.     // Errors:
  1106.     //    badComponentInstance    invalid scripting component instance
  1107.     //     errOSASystemError
  1108.  
  1109. #define typeOSADialectInfo                'difo'
  1110.     // Type of a dialect info record containing at least keyOSADialectName
  1111.     // and keyOSADialectCode fields.
  1112.  
  1113. // keys for dialect info record, also used as selectors to OSAGetDialectInfo.
  1114.  
  1115. #define keyOSADialectName                'dnam'
  1116.     // Field of a typeOSADialectInfo record of typeChar.
  1117. #define keyOSADialectCode                'dcod'
  1118.     // Field of a typeOSADialectInfo record of typeShortInteger.
  1119. #define keyOSADialectLangCode            'dlcd'
  1120.     // Field of a typeOSADialectInfo record of typeShortInteger.
  1121. #define keyOSADialectScriptCode            'dscd'
  1122.     // Field of a typeOSADialectInfo record of typeShortInteger.
  1123.  
  1124. ////////////////////////////////////////////////////////////////////////////////
  1125. // OSA Optional Event Handling Interface
  1126. ////////////////////////////////////////////////////////////////////////////////
  1127. // Scripting components that support the Event Handling interface have the 
  1128. // kOSASupportsEventHandling bit set in it's ComponentDescription.
  1129. ////////////////////////////////////////////////////////////////////////////////
  1130.  
  1131. typedef pascal OSErr (*AEHandlerProcPtr)(const AppleEvent*        theAppleEvent,
  1132.                                          AppleEvent*            reply,
  1133.                                          long                    refCon);
  1134.  
  1135. pascal OSAError
  1136. OSASetResumeDispatchProc(ComponentInstance        scriptingComponent,
  1137.                          AEHandlerProcPtr        resumeDispatchProc,
  1138.                          long                    refCon)
  1139.     OSAComponentFunctionInline(kOSASelectSetResumeDispatchProc, 8);
  1140.     // This function is used to set the ResumeDispatchProc that will be used
  1141.     // by OSAExecuteEvent and OSADoEvent if either no event handler can be
  1142.     // found in the context, or the context event hander "continues" control
  1143.     // onward. The two constants kOSAUseStandardDispatch and kOSANoDispatch
  1144.     // may also be passed to this routine indicating that the handler registered
  1145.     // in the application with AEInstallEventHandler should be used, or no
  1146.     // dispatch should occur, respectively.
  1147.     //
  1148.     // Errors:
  1149.     //    badComponentInstance    invalid scripting component instance
  1150.     //     errOSASystemError
  1151.  
  1152. #define kOSAUseStandardDispatch        ((AEHandlerProcPtr)kAEUseStandardDispatch)
  1153.     // Special ResumeDispatchProc constant which may be passed to 
  1154.     // OSASetResumeDispatchProc indicating that the handler registered
  1155.     // in the application with AEInstallEventHandler should be used.
  1156.  
  1157. #define kOSANoDispatch                ((AEHandlerProcPtr)kAENoDispatch)
  1158.     // Special ResumeDispatchProc constant which may be passed to 
  1159.     // OSASetResumeDispatchProc indicating that no dispatch should occur.
  1160.  
  1161. #define kOSADontUsePhac                0x0001
  1162.     // Special refCon constant that may be given to OSASetResumeDispatchProc
  1163.     // only when kOSAUseStandardDispatch is used as the ResumeDispatchProc.
  1164.     // This causes the standard dispatch to be performed, except the phac
  1165.     // handler is not called.  This is useful during tinkerability, when
  1166.     // the phac handler is used to lookup a context associated with an event's 
  1167.     // direct parameter, and call OSAExecuteEvent or OSADoEvent.  Failure to
  1168.     // bypass the phac handler would result in an infinite loop.
  1169.  
  1170. pascal OSAError
  1171. OSAGetResumeDispatchProc(ComponentInstance        scriptingComponent,
  1172.                          AEHandlerProcPtr*        resumeDispatchProc,
  1173.                          long*                    refCon)
  1174.     OSAComponentFunctionInline(kOSASelectGetResumeDispatchProc, 8);
  1175.     // Returns the registered ResumeDispatchProc.  If no ResumeDispatchProc has
  1176.     // been registered, then kOSAUseStandardDispatch (the default) is returned.
  1177.     //
  1178.     // Errors:
  1179.     //    badComponentInstance    invalid scripting component instance
  1180.     //     errOSASystemError
  1181.  
  1182. pascal OSAError
  1183. OSAExecuteEvent(ComponentInstance    scriptingComponent,
  1184.                 const AppleEvent*    theAppleEvent,
  1185.                 OSAID                contextID,
  1186.                 long                modeFlags,
  1187.                 OSAID*                resultingScriptValueID)
  1188.     OSAComponentFunctionInline(kOSASelectExecuteEvent, 16);
  1189.     // This call is similar to OSAExecute except the initial command to
  1190.     // execute comes in the form of an AppleEvent.  If the contextID
  1191.     // defines any event handlers for that event, they are used to process
  1192.     // the event.  If no event handler can be found in the context
  1193.     // errAEEventNotHandled is returned.  If an event handler is found and
  1194.     // the hander "continues" control onward, the ResumeDispatchProc
  1195.     // (registered with OSASetResumeDispatchProc, above) is called given the
  1196.     // AppleEvent.  The result is returned as a scriptValueID.
  1197.     //
  1198.     // Errors:
  1199.     //    badComponentInstance    invalid scripting component instance
  1200.     //     errOSASystemError
  1201.     //     errOSAInvalidID
  1202.     //     errOSAScriptError:        the executing script got an error
  1203.     //     errAEEventNotHandled:    no handler for event in contextID
  1204.     //
  1205.     // ModeFlags:
  1206.     //    kOSAModeNeverInteract
  1207.     //    kOSAModeCanInteract
  1208.     //    kOSAModeAlwaysInteract
  1209.     //    kOSAModeCantSwitchLayer
  1210.     //    kOSAModeDontReconnect
  1211.     //    kOSAModeDoRecord
  1212.  
  1213. pascal OSAError
  1214. OSADoEvent(ComponentInstance    scriptingComponent,
  1215.            const AppleEvent*    theAppleEvent,
  1216.            OSAID                contextID,
  1217.            long                    modeFlags,
  1218.            AppleEvent*            reply)
  1219.     OSAComponentFunctionInline(kOSASelectDoEvent, 16);
  1220.     // This call is similar to OSADoScript except the initial command to
  1221.     // execute comes in the form of an AppleEvent, and the result is an 
  1222.     // AppleEvent reply record.  If the contextID defines any event handlers
  1223.     // for that event, they are used to process the event.  If no event handler
  1224.     // can be found in the context errAEEventNotHandled is returned.  If an
  1225.     // event handler is found and the hander "continues" control onward, the
  1226.     // ResumeDispatchProc (registered with OSASetResumeDispatchProc, above) is
  1227.     // called given the AppleEvent.  The result is returned in the form of an
  1228.     // AppleEvent reply descriptor. If at any time the script gets an error, or
  1229.     // if the ResumeDispatchProc returns a reply event indicating an error,
  1230.     // then the OSADoEvent call itself returns an error reply (i.e. OSADoEvent
  1231.     // should never return errOSAScriptError).  Any error result returned by
  1232.     // the ResumeDispatchProc will be returned by OSADoEvent.
  1233.     //
  1234.     // Errors:
  1235.     //    badComponentInstance    invalid scripting component instance
  1236.     //     errOSASystemError
  1237.     //     errOSAInvalidID
  1238.     //     errAEEventNotHandled:    no handler for event in contextID
  1239.     //
  1240.     // ModeFlags:
  1241.     //    kOSAModeNeverInteract
  1242.     //    kOSAModeCanInteract
  1243.     //    kOSAModeAlwaysInteract
  1244.     //    kOSAModeCantSwitchLayer
  1245.     //    kOSAModeDontReconnect
  1246.     //    kOSAModeDoRecord
  1247.  
  1248. pascal OSAError
  1249. OSAMakeContext(ComponentInstance    scriptingComponent,
  1250.                const AEDesc*        contextName,
  1251.                OSAID                parentContext,
  1252.                OSAID*                resultingContextID)
  1253.     OSAComponentFunctionInline(kOSASelectMakeContext, 12);
  1254.     // Makes a new empty context which may be passed to OSAExecute or 
  1255.     // OSAExecuteEvent.  If contextName is typeNull, an unnamed context is
  1256.     // created. If parentContext is kOSANullScript then the resulting context
  1257.     // does not inherit bindings from any other context.
  1258.     //
  1259.     // Errors:
  1260.     //    badComponentInstance    invalid scripting component instance
  1261.     //     errOSASystemError
  1262.     //     errOSAInvalidID
  1263.     //     errAECoercionFail:        contextName is invalid
  1264.  
  1265. ////////////////////////////////////////////////////////////////////////////////
  1266. #ifdef __cplusplus
  1267. }
  1268. #endif
  1269. // You're still here?  Go home.
  1270. #endif
  1271. ////////////////////////////////////////////////////////////////////////////////
  1272.